34.1 开发容器配置

13 分钟阅读

学习如何在企业环境中配置和使用 Claude Code 开发容器，为团队提供一致、安全的开发环境。

34.1.1 开发容器概述#

什么是开发容器#

开发容器（Dev Containers）是一种使用 Docker 容器作为完整开发环境的解决方案。它为团队提供：

  • 一致性：所有开发者使用相同的工具和配置
  • 可移植性：在不同操作系统上获得相同的开发体验
  • 隔离性：开发环境与主机系统分离
  • 安全性：增强的安全措施保护开发环境

Claude Code 开发容器特性#

Claude Code 提供的官方开发容器包含：

  • 生产就绪的 Node.js：基于 Node.js 20 构建
  • 安全设计：自定义防火墙限制网络访问
  • 开发者工具：git、ZSH、fzf 等生产力工具
  • VS Code 集成：预配置的扩展和优化设置
  • 会话持久性：保留命令历史和配置

34.1.2 快速入门#

前置要求#

确保您的系统已安装以下组件：

检查 Docker 安装

docker --version

检查 VS Code 安装

code --version

检查 Remote - Containers 扩展

code --list-extensions | grep ms-vscode-remote.remote-containers

安装步骤#

  1. 安装 Docker Desktop
bash
bash

# macOS
brew install --cask docker

# 启动 Docker Desktop
open /Applications/Docker.app

# 安装 VS Code（如果尚未安装）
brew install --cask visual-studio-code
# 安装 Remote - Containers 扩展
code --install-extension ms-vscode-remote.remote-containers
  1. 克隆 Claude Code 参考实现
bash
bash

git clone https://github.com/anthropics/claude-code.git
cd claude-code

在 VS Code 中：
> - 打开命令面板：`Cmd+Shift+P`
> - 输入并选择：`Remote-Containers: Reopen in Container`
> - 等待容器构建和启动

## 34.1.3 开发容器配置详解

### devcontainer.json 配置

{
"name": "Claude Code Dev Container",
"dockerFile": "Dockerfile",
"context": "..",
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"github.copilot"
],
"settings": {
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"terminal.integrated.defaultProfile.linux": "zsh"
}
}
},
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "20"
},
"ghcr.io/devcontainers/features/git:1": {}
},
"mounts": [
"source=${localWorkspaceFolder},target=/workspace,type=bind",
"source=claude-code-history,target=/home/vscode/.claude-history,type=volume"
],
"postCreateCommand": "bash .devcontainer/init-firewall.sh",
"remoteUser": "vscode"
}

Dockerfile 配置#

bash
dockerfile

FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04

# 安装 Node.js 20
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

# 安装开发工具
RUN apt-get update && apt-get install -y \
    git \
    zsh \
    fzf \
    ripgrep \
    jq \
    curl \
    wget \
    vim \
    && apt-get clean && rm -rf /var/lib/apt/lists/*

# 安装 Oh My Zsh
RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended

# 配置 ZSH
RUN echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && \
    echo 'export EDITOR="vim"' >> ~/.zshrc

# 创建非 root 用户
RUN useradd -m -s /bin/zsh vscode && \
    echo "vscode ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers

# 设置工作目录
WORKDIR /workspace

USER vscode

### 防火墙脚本 (init-firewall.sh)

#!/bin/bash
set -e
echo "配置开发容器防火墙..."
# 安装 iptables
sudo apt-get update
sudo apt-get install -y iptables
# 清除现有规则
sudo iptables -F
sudo iptables -X
sudo iptables -t nat -F
sudo iptables -t nat -X
# 默认策略：拒绝所有出站连接
sudo iptables -P OUTPUT DROP
# 允许本地回环
sudo iptables -A OUTPUT -o lo -j ACCEPT
# 允许已建立的连接
sudo iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
# 允许 DNS
sudo iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT
# 允许 SSH
sudo iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT
# 允许 HTTPS（白名单域名）
ALLOWED_DOMAINS=(
"api.anthropic.com"
"code.claude.com"
"github.com"
"npmjs.org"
"registry.npmjs.org"
"cdn.npmjs.org"
)
for domain in "${ALLOWED_DOMAINS[@]}"; do
ip=$(dig +short $domain | head -n 1)
if [ -n "$ip" ]; then
sudo iptables -A OUTPUT -d $ip -p tcp --dport 443 -j ACCEPT
echo "允许访问: $domain ($ip)"
fi
done
# 保存规则
sudo iptables-save > /etc/iptables/rules.v4
echo "防火墙配置完成"

34.1.4 企业级自定义配置#

多环境配置#

为不同的开发环境创建不同的配置文件：

bash
bash

.devcontainer/
├── devcontainer.json
├── Dockerfile
├── Dockerfile.dev
├── Dockerfile.staging
├── Dockerfile.prod
├── devcontainer.dev.json
├── devcontainer.staging.json
└── devcontainer.prod.json

{
"name": "Claude Code Dev Environment",
"dockerFile": "Dockerfile.dev",
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"github.copilot",
"eamodio.gitlens",
"ms-python.python"
]
}
},
"mounts": [
"source=${localWorkspaceFolder},target=/workspace,type=bind",
"source=dev-node-modules,target=/workspace/node_modules,type=volume"
],
"postCreateCommand": "npm install && npm run setup:dev"
}

生产环境配置 (devcontainer.prod.json):

bash
json

{
  "name": "Claude Code Prod Environment",
  "dockerFile": "Dockerfile.prod",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode",
        "ms-vscode.vscode-typescript-next"
      ]
    }
  },
  "mounts": [
    "source=${localWorkspaceFolder},target=/workspace,type=bind"
  ],
  "postCreateCommand": "npm ci && npm run build"
}

### 企业级 Dockerfile

FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04
# 设置时区
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
# 安装企业级工具
RUN apt-get update && apt-get install -y \
# 基础工具
git \
curl \
wget \
vim \
jq \
# 开发工具
build-essential \
python3 \
python3-pip \
# 安全工具
openssl \
gnupg \
# 网络工具
net-tools \
iputils-ping \
# 版本控制
subversion \
mercurial \
&& apt-get clean && rm -rf /var/lib/apt/lists/*
# 安装 Node.js 20
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
apt-get install -y nodejs && \
apt-get clean && rm -rf /var/lib/apt/lists/*
# 配置 npm 企业镜像
RUN npm config set registry https://npm.company.com && \
npm config set @company:registry https://npm.company.com
# 安装企业证书
COPY company-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates
# 安装企业 CLI 工具
RUN npm install -g @company/cli-tools
# 配置 Git
RUN git config --global user.name "Company Developer" && \
git config --global user.email "dev@company.com" && \
git config --global core.autocrlf input
# 安装 Oh My Zsh 和企业主题
RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended && \
git clone https://github.com/company/zsh-theme.git ~/.oh-my-zsh/custom/themes/company
# 配置企业代理
ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080
ENV NO_PROXY=localhost,127.0.0.1,.company.com
# 创建用户
RUN useradd -m -s /bin/zsh vscode && \
echo "vscode ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
WORKDIR /workspace
USER vscode
# 配置企业环境变量
RUN echo 'export COMPANY_ENV=production' >> ~/.zshrc && \
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

团队协作配置#

共享配置文件 (.devcontainer/shared-settings.json):

bash
json

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,
  "files.exclude": {
    "**/.git": true,
    "**/.DS_Store": true,
    "**/node_modules": true,
    "**/dist": true
  },
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/.git": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "eslint.workingDirectories": ["./"]
}

{
"recommendations": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode",
"ms-vscode.vscode-typescript-next",
"eamodio.gitlens",
"ms-python.python",
"github.copilot",
"github.vscode-pull-request-github",
"redhat.vscode-yaml",
"ms-azuretools.vscode-docker"
]
}

34.1.5 安全增强配置#

强化防火墙规则#

bash
bash

#!/bin/bash
# .devcontainer/init-security.sh

set -e

echo "配置企业级安全防火墙..."

# 安装安全工具
sudo apt-get update
sudo apt-get install -y iptables fail2ban

# 配置 iptables
sudo iptables -F
sudo iptables -X
sudo iptables -t nat -F
sudo iptables -t nat -X

# 默认拒绝策略
sudo iptables -P INPUT DROP
sudo iptables -P FORWARD DROP
sudo iptables -P OUTPUT DROP

# 允许本地回环
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT

# 允许已建立的连接
sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A OUTPUT -m state --state ESTABLISHED,RELATED -j ACCEPT

# 允许 DNS
sudo iptables -A OUTPUT -p udp --dport 53 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 53 -j ACCEPT

# 允许 SSH（仅从特定网络）
sudo iptables -A INPUT -p tcp -s 10.0.0.0/8 --dport 22 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 22 -j ACCEPT

# 企业白名单域名
declare -A ALLOWED_DOMAINS=(
    ["api.anthropic.com"]="443"
    ["code.claude.com"]="443"
    ["github.com"]="443"
    ["npm.company.com"]="443"
    ["git.company.com"]="443"
    ["artifacts.company.com"]="443"
)

for domain in "${!ALLOWED_DOMAINS[@]}"; do
    port=${ALLOWED_DOMAINS[$domain]}
    ips=$(dig +short $domain)
    for ip in $ips; do
        sudo iptables -A OUTPUT -d $ip -p tcp --dport $port -j ACCEPT
        echo "允许: $domain -> $ip:$port"
    done
done

# 阻止常见攻击端口
BLOCKED_PORTS=(23 135 137 138 139 445 1433 3389)
for port in "${BLOCKED_PORTS[@]}"; do
    sudo iptables -A OUTPUT -p tcp --dport $port -j DROP
    sudo iptables -A OUTPUT -p udp --dport $port -j DROP
done

# 保存规则
sudo iptables-save > /etc/iptables/rules.v4

# 配置 fail2ban
sudo cat > /etc/fail2ban/jail.local << 'EOF'
[DEFAULT]
bantime = 3600
findtime = 600
maxretry = 5

[sshd]
enabled = true
port = ssh
filter = sshd
logpath = /var/log/auth.log
maxretry = 3
EOF

sudo systemctl enable fail2ban
sudo systemctl start fail2ban

echo "安全配置完成"

### 文件系统权限配置

#!/bin/bash
# .devcontainer/init-permissions.sh
set -e
echo "配置文件系统权限..."
# 创建受限目录结构
sudo mkdir -p /workspace/{src,tests,docs,scripts}
sudo mkdir -p /workspace/.secrets
# 设置权限
sudo chown -R vscode:vscode /workspace
sudo chmod 755 /workspace/{src,tests,docs,scripts}
sudo chmod 700 /workspace/.secrets
# 配置 .gitignore
cat > /workspace/.gitignore << 'EOF'
# Secrets
.secrets/
*.key
*.pem
.env.local
# IDE
.vscode/
.idea/
# OS
.DS_Store
Thumbs.db
# Dependencies
node_modules/
EOF
# 配置敏感文件保护
sudo touch /workspace/.secrets/.gitkeep
sudo chmod 600 /workspace/.secrets/.gitkeep
echo "文件系统权限配置完成"

34.1.6 CI/CD 集成#

GitHub Actions 配置#

bash
yaml

name: Dev Container CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v3

    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v2

    - name: Build dev container
      uses: devcontainers/ci@v0.3
      with:
        push: never
        imageName: ghcr.io/${{ github.repository }}/devcontainer
        cacheFrom: ghcr.io/${{ github.repository }}/devcontainer:latest

    - name: Run tests in dev container
      uses: devcontainers/ci@v0.3
      with:
        push: never
        imageName: ghcr.io/${{ github.repository }}/devcontainer
        runCmd: npm test

### GitLab CI 配置

stages:
- build
- test
variables:
DEV_CONTAINER_IMAGE: $CI_REGISTRY_IMAGE/devcontainer:$CI_COMMIT_SHORT_SHA
build:
stage: build
image: docker:24
services:
- docker:24-dind
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -f .devcontainer/Dockerfile -t $DEV_CONTAINER_IMAGE .
- docker push $DEV_CONTAINER_IMAGE
test:
stage: test
image: $DEV_CONTAINER_IMAGE
script:
- npm install
- npm test
- npm run lint

34.1.7 监控和日志#

容器健康检查#

bash
json

{
  "name": "Claude Code Dev Container",
  "dockerFile": "Dockerfile",
  "healthCheck": {
    "test": ["CMD", "curl", "-f", "http://localhost:3000/health"],
    "interval": "30s",
    "timeout": "10s",
    "retries": 3,
    "startPeriod": "40s"
  }
}

### 日志配置

#!/bin/bash
# .devcontainer/init-logging.sh
# 创建日志目录
mkdir -p /workspace/logs
# 配置日志轮转
sudo cat > /etc/logrotate.d/devcontainer << 'EOF'
/workspace/logs/*.log {
daily
rotate 7
compress
delaycompress
missingok
notifempty
create 0644 vscode vscode
}
EOF
# 配置应用日志
cat > /workspace/.env << 'EOF'
LOG_LEVEL=info
LOG_FILE=/workspace/logs/app.log
LOG_MAX_SIZE=10m
LOG_MAX_FILES=5
EOF
echo "日志配置完成"

34.1.8 最佳实践#

1. 版本控制#

  • 将所有配置文件纳入版本控制
  • 使用 .gitignore 排除敏感信息
  • 使用环境变量管理配置差异

2. 文档化#

  • 为每个配置文件添加注释
  • 创建 README 说明如何使用开发容器
  • 记录常见问题和解决方案

3. 安全性#

  • 定期更新基础镜像
  • 使用最小权限原则
  • 定期审计防火墙规则

4. 性能优化#

  • 使用多阶段构建减小镜像大小
  • 利用 Docker 缓存层
  • 合理配置资源限制

5. 团队协作#

  • 标准化配置文件
  • 共享常用扩展和设置
  • 建立配置审查流程

34.1.9 故障排查#

常见问题#

问题 1：容器无法启动

bash
bash

# 检查 Docker 状态
docker ps -a

# 查看容器日志
docker logs <container-id>

重新构建容器

在 VS Code 中: Remote-Containers: Rebuild Container

检查防火墙规则

sudo iptables -L -n -v

测试 DNS 解析

dig api.anthropic.com

检查代理配置

echo $HTTP_PROXY echo $HTTPS_PROXY

bash
**问题 3：权限问题**

bash

检查文件权限

ls -la /workspace

修复权限

sudo chown -R vscode:vscode /workspace

问题 4：扩展安装失败

手动安装扩展

code --install-extension <extension-id>

检查扩展市场连接

curl -I https://marketplace.visualstudio.com

标记本节教程为已读

记录您的学习进度，方便后续查看。

上一节33.2 LiteLLM 网关部署下一节 34.2 沙箱隔离配置